node-res

Node Res

A facade over Node.js HTTP res object with no side-effects.

node-res is a simple module to make HTTP response in Node.js. It offers helpers to make it easier to set headers, define response statuses and properly parse response type to set appropriate headers.

For example:

// content-type: plain/text
nodeRes.send(req, res, 'Hello world')

// content-type: application/json
nodeRes.send(req, res, { greeting: 'hello world' })
    
// content-type: text/html
nodeRes.send(req, res, '<h2> Hello world </h2>')

See also

• node-req
• node-cookie

Basic Example

const http = require('http')
const nodeRes = require('node-res')

http.createServer(function (req, res) {
  
  // plain text
  nodeRes.send(req, res, "Hello world")

  // json
  nodeRes.json(req, res, {time:"now"})

  // jsonp
  nodeRes.jsonp(req, res, {time:"now"}, "callback")

}).listen(3000)

API

Response

A simple IO module to make consistent HTTP response, without worrying about underlying details.

• Response
  • ~getHeader(res, key) ⇒ Array | String
  • ~header(res, key, value) ⇒ void
  • ~append(res, key, value) ⇒ void
  • ~status(res, code) ⇒ void
  • ~safeHeader(res, key, value) ⇒ void
  • ~removeHeader(res, key) ⇒ void
  • ~write(res, body) ⇒ void
  • ~end(res, [payload]) ⇒ void
  • ~send(req, res, body, [generateEtag]) ⇒ void
  • ~etag(res, body) ⇒ void
  • ~prepare(res, body) ⇒ String
  • ~prepareJsonp(res, body, callbackFn) ⇒ String
  • ~json(req, res, body, [generateEtag]) ⇒ void
  • ~jsonp(req, res, body, [callbackFn], [generateEtag]) ⇒ void
  • ~location(res, url) ⇒ void
  • ~redirect(req, res, url, [status]) ⇒ void
  • ~vary(res, field) ⇒ void
  • ~type(req, res, [charset]) ⇒ void
  • ~stream(res, body) ⇒ Promise

Response~getHeader(res, key) ⇒ Array | String

Returns the value of an existing header on the response object

Kind: inner method of Response
Returns: Array | String - Return type depends upon the header existing value

Param	Type
res	ServerResponse
key	String

Example

nodeRes.getHeader(res, 'Content-type')

Response~header(res, key, value) ⇒ void

Sets header on the response object. This method will wipe off existing values. To append to existing values, use append.

Kind: inner method of Response

Param	Type
res	http.ServerResponse
key	String
value	String | Array

Example

nodeRes.header(res, 'Content-type', 'application/json')

// or set an array of headers
nodeRes.header(res, 'Link', ['<http://localhost/>', '<http://localhost:3000/>'])

Response~append(res, key, value) ⇒ void

Appends value to the header existing values.

Kind: inner method of Response

Param	Type
res	http.ServerResponse
key	String
value	String | Array

Example

nodeRes.append(res, 'Content-type', 'application/json')

// or append an array of headers
nodeRes.append(res, 'Link', ['<http://localhost/>', '<http://localhost:3000/>'])

Response~status(res, code) ⇒ void

Set status on the HTTP res object

Kind: inner method of Response

Param	Type
res	http.ServerResponse
code	Number

Example

nodeRes.status(res, 200)

Response~safeHeader(res, key, value) ⇒ void

Sets the header on response object, only if it does not exists.

Kind: inner method of Response

Param	Type
res	http.ServerResponse
key	String
value	String | Array

Example

nodeRes.safeHeader(res, 'Content-type', 'application/json')

Response~removeHeader(res, key) ⇒ void

Removes the header from response

Kind: inner method of Response

Param	Type
res	http.ServerResponse
key	String

Example

nodeRes.removeHeader(res, 'Content-type')

Response~write(res, body) ⇒ void

Write string or buffer to the response object.

Kind: inner method of Response

Param	Type
res	http.ServerResponse
body	String | Buffer

Example

nodeRes.write(res, 'Hello world')

Response~end(res, [payload]) ⇒ void

Explictly end HTTP response

Kind: inner method of Response

Param	Type
res	http.ServerResponse
[payload]	String | Buffer

Example

nodeRes.end(res, 'Hello world')

Response~send(req, res, body, [generateEtag]) ⇒ void

Send body as the HTTP response and end it. Also this method will set the appropriate Content-type and Content-length.

If body is set to null, this method will end the response as 204.

Kind: inner method of Response

Param	Type	Default
req	http.ServerRequest
res	http.ServerResponse
body	String | Buffer | Object | Stream
[generateEtag]	Boolean	true

Example

nodeRes.send(req, res, 'Hello world')

// or html
nodeRes.send(req, res, '<h2> Hello world </h2>')

// or JSON
nodeRes.send(req, res, { greeting: 'Hello world' })

// or Buffer
nodeRes.send(req, res, Buffer.from('Hello world', 'utf-8'))

// Ignore etag
nodeRes.send(req, res, 'Hello world', false)

Response~etag(res, body) ⇒ void

Sets the Etag header for a given body chunk

Kind: inner method of Response

Param	Type
res	http.ServerResponse
body	String | Buffer

Example

nodeRes.etag(res, 'Hello world')

Response~prepare(res, body) ⇒ String

Prepares the response body by encoding it properly. Also sets appropriate headers based upon the body content type.

This method is used internally by send, so you should never use it when calling send.

It is helpful when you want to get the final payload and end the response at a later stage.

Kind: inner method of Response

Param	Type
res	http.ServerResponse
body	Mixed

Example

const chunk = nodeRes.prepare(res, '<h2> Hello </h2>')

if (chunk) {
  nodeRes.etag(res, chunk)

  if (nodeReq.fresh(req, res)) {
    chunk = null
    nodeRes.status(304)
  }

  nodeRes.end(chunk)
}

Response~prepareJsonp(res, body, callbackFn) ⇒ String

Prepares response for JSONP

Kind: inner method of Response

Param	Type
res	http.ServerResponse
body	Object
callbackFn	String

Example

const chunk = nodeRes.prepareJsonp(res, '<h2> Hello </h2>', 'callback')

if (chunk) {
  nodeRes.etag(res, chunk)

  if (nodeReq.fresh(req, res)) {
    chunk = null
    nodeRes.status(304)
  }

  nodeRes.end(chunk)
}

Response~json(req, res, body, [generateEtag]) ⇒ void

Returns the HTTP response with Content-type set to application/json.

Kind: inner method of Response

Param	Type	Default
req	http.IncomingMessage
res	http.ServerResponse
body	Object
[generateEtag]	Boolean	true

Example

nodeRes.json(req, res, { name: 'virk' })
nodeRes.json(req, res, [ 'virk', 'joe' ])

Response~jsonp(req, res, body, [callbackFn], [generateEtag]) ⇒ void

Make JSONP response with Content-type set to text/javascript.

Kind: inner method of Response

Param	Type	Default
req	http.IncomingMessage
res	http.ServerResponse
body	Object
[callbackFn]	String	'callback'
[generateEtag]	Boolean	true

Example

nodeRes.jsonp(req, res, { name: 'virk' }, 'callback')

Response~location(res, url) ⇒ void

Set Location header on the HTTP response.

Kind: inner method of Response

Param	Type
res	http.ServerResponse
url	String

Response~redirect(req, res, url, [status]) ⇒ void

Redirect the HTTP request to the given url.

Kind: inner method of Response

Param	Type	Default
req	http.IncomingMessage
res	http.ServerResponse
url	String
[status]	Number	302

Example

nodeRes.redirect(req, res, '/')

Response~vary(res, field) ⇒ void

Add vary header to the HTTP response.

Kind: inner method of Response

Param	Type
res	http.ServerResponse
field	String

Response~type(req, res, [charset]) ⇒ void

Set content type header by looking up the actual type and setting charset to utf8.

Note

When defining custom charset, you must set pass the complete content type, otherwise false will be set as the content-type header.

Kind: inner method of Response

Param	Type
req	http.IncomingMessage
res	http.ServerResponse
[charset]	String

Example

nodeRes.type(res, 'html')

nodeRes.type(res, 'json')

nodeRes.type(res, 'text/html', 'ascii')

Response~stream(res, body) ⇒ Promise

Pipe stream to the response. Also this method will make sure to destroy the stream, if request gets cancelled.

The promise resolve when response finishes and rejects, when stream raises errors.

Kind: inner method of Response

Param	Type
res	Object
body	Stream

Example

Response.stream(res, fs.createReadStream('foo.txt'))

// handle stream errors
Response
  .stream(res, fs.createReadStream('foo.txt'))
  .catch((error) => {
  })